Copyright (c) 1996, 1997 by John Montbriand. All Rights Reserved.
Permission hereby granted for public use.
Distribute freely in areas where the laws of copyright apply.
USE AT YOUR OWN RISK.
DO NOT DISTRIBUTE MODIFIED COPIES.
Comments/questions/postcards* to the author at the address:
John Montbriand
P.O. Box. 1133
Saskatoon Saskatchewan Canada
S7K 3N2
or by email at:
tinyjohn@sk.sympatico.ca
*if you mail a postcard, then I will provide you with technical support
regarding questions you may have about this file.
1.1 Changes:
Added documentation for the PixMap2PixPat routine.
Simplified GDevice creation code.
Contents
About PixMaps...
Implementation Notes
Materials
Creating and Disposing of PixMaps
MakePixMap
Make16BitPixMap and Make32BitPixMap
MakeScreenLikePixMap
KillPixMap
PixMap Information Access
PixMapSize
SetPixMapPixel and GetPixMapPixel
CalcPixMapColours
Flips and Rotates for PixMaps
RotatePixRight
RotatePixLeft
FlipPixVertical
FlipPixHorizontal
RotatePixMap
DuplicatePixMap
Converting Pictures to PixMaps
PICTToPixMap, PICTTo16BitPixMap, and PICTTo32BitPixMap
Converting PixMaps to Pictures
PixMapToPICT
PixMapToCompressedPICT
Converting PixMaps to Pixel Patterns
PixMap2PixPat
A Macro for Drawing Into PixMaps
WithPixMap
Drawing and Plotting Routines
PlotPixMap
PixMapCopy
Files in this package
Copies for sale!
NO WARRANTY
Bug reports make this a better product!
Further Reference
Other
About PixMaps...
PixMaps define a data type used for the storage, retrieval, and display of 1, 2, 4, 8,16, and 32 bit raster data on Mac OS compatible computers. QuickDraw drawing routines can be used to draw directly into PixMaps, and PixMaps can be used for both black and white and color images. PixMaps allow you to do color off-screen drawing. Drawing things off screen and then placing them on screen creates the feel of instantaneous, flicker free drawing.
QuickDraw CGrafPorts draw into PixMap structures, and, as a matter of fact, all screen drawing on newer Mac OS compatible computers is implemented through PixMaps that are memory mapped to the screen hardware. PixMaps are an extension of the BitMap, and can be, for most purposes, used interchangeably.
Routines and methods used herein are similar to the corresponding routines found in the BitMaps package.
Implementation Notes
KillPixMap can be called from GrowZone functions.
The implementation for many of the routines herein 'special cases' some operations for different PixMap depths (i.e. 1, 2, 4, 8, 16, and 32 bit ones) for performance reasons.
Materials
The PixMap definition is the copyright property of Apple Computer and has been known to the public since 1986.
The routines documented herein are the copyright property of John Montbriand. I am making these routines available to the Mac OS programming community because I feel it's about time someone did! They're fun, easy to use, and practical. I hope all who find them will use them well.
Creating and Disposing of PixMaps
PixMaps can be created for a specific depth or as the closest match for a specific area on the screen. Routines for creating PixMaps are as follows:
MakePixMap
PixMapHandle MakePixMap(short width, short height, CTabHandle clut);
MakePixMap creates a new PixMap handle with the requested dimensions. If there is not enough memory to allocate the PixMap, MakePixMap will return NULL. if clut is NULL, then the default 256 color table (clut = 8) is used. if clut is not NULL, then a copy of it is used in the PixMap. The number of colors in the clut determines the pixel depth of the created PixMap as follows:
2 colors -> 1 pit per pixel,
3 to 4 colors -> 2 bits per pixel,
5 to 16 colors -> 4 bits per pixel,
17 to 256 colors -> 8 bits per pixel.
EXAMPLE:
PixMapHandle pix;
pix = MakePixMap(100, 100, NULL);
if (pix == NULL) { err = memFullErr; goto bail; }
Make16BitPixMap and Make32BitPixMap
PixMapHandle Make16BitPixMap(short width, short height);
PixMapHandle Make32BitPixMap(short width, short height);
Make16BitPixMap creates a new PixMap handle with the requested dimensions. If there is not enough memory to allocate the PixMap, Make16BitPixMap will return NULL. The created PixMap utilizes 16 bit color and allocates 16 bits per each pixel. Make32BitPixMap is identical however it allocates 32 bits per pixel.
MakeScreenLikePixMap creates a PixMap mirroring the attributes of the PixMap used to draw largest area of *globalRect on the screen.
EXAMPLE:
PixMapHandle pix;
Rect r;
WindowPtr w;
SetPort(w);
r = w->portRect;
LocalToGlobal((Point*) &r.top);
LocalToGlobal((Point*) &r.bottom);
pix = MakeScreenLikePixMap(&r);
if (pix == NULL) { err = memFullErr; goto bail; }
KillPixMap
void KillPixMap(PixMapHandle pix);
KillPixMap disposes of a PixMap allocated by one of the routines herein.
EXAMPLE:
PixMapHandle pix;
pix = Make16BitPixMap(100, 100, NULL);
if (pix == NULL) { err = memFullErr; goto bail; }
....
KillPixMap(pix);
PixMap Information Access
PixMapSize
long PixMapSize(PixMapHandle pix);
PixMapSize returns the number of bytes occupied by the PixMap, its color table, and its raster data.
EXAMPLE:
PixMapHandle pix;
long bytecount;
pix = Make16BitPixMap(100, 100, NULL);
if (pix == NULL) { err = memFullErr; goto bail; }
bytecount = PixMapSize(pix);
SetPixMapPixel and GetPixMapPixel
void SetPixMapPixel(PixMapHandle pix, short h, short v, long value);
long GetPixMapPixel(PixMapHandle pix, short h, short v);
SetPixMapPixel and GetPixMapPixel are for getting or setting individual pixel values.
EXAMPLE:
PixMapHandle pix;
long pixelvalue;
pix = Make16BitPixMap(100, 100, NULL);
if (pix == NULL) { err = memFullErr; goto bail; }
pixelvalue = GetPixMapPixel(pix, 25, 32);
CalcPixMapColours
CTabHandle CalcPixMapColours(PixMapHandle pix);
CalcPixMapColours calculates a color table for the colors used in the PixMap. For indexed images, this routine returns a copy of the PixMap's color table, otherwise, for direct images, it calls GetPixMapInfo.
RotatePixRight creates a new PixMap containing the image stored in the parameter PixMap rotated 90 degrees to the right. The resulting PixMap is appropriately sized: i.e. if the source PixMap is 100 pixels wide and 200 pixels tall, then the result PixMap pointer will be 200 pixels wide and 100 pixels tall. If an error occurs, RotatePixRight returns NULL.
RotatePixLeft creates a new PixMap containing the image stored in the parameter bitmap pointer rotated 90 degrees to the left. The resulting PixMap is appropriately sized: i.e. if the source PixMap is 100 pixels wide and 200 pixels tall, then the result PixMap pointer will be 200 pixels wide and 100 pixels tall. If an error occurs, RotatePixLeft returns NULL.
FlipPixVertical creates a new PixMap containing the image stored in the parameter PixMap flipped upside down. The resulting PixMap will be the same size as the original image.
FlipPixHorizontal creates a new PixMap containing the image stored in the parameter PixMap flipped horizontally. The resulting PixMap will be the same size as the original image.
PixMapHandle RotatePixMap(PixMapHandle pix, short cx, short cy, float angle);
RotatePixMap creates a new PixMap containing the image from the parameter PixMap rotated angle degrees about the center (cx, cy). The resultant PixMap will have the same dimensions as the parameter PixMap regardless of the angle specified.
PICTToPixMap, PICTTo16BitPixMap, or PICTTo32BitPixMap create a new PixMap the using the size information provided in the QuickDraw picture pointer parameter and draws the picture in the PixMap before returning the PixMap.
EXAMPLE:
PixMapHandle pix;
PicHandle pic;
pic = GetPicture(128);
if (pic == NULL) {
err = ResError();
if (err == noErr) err = resNotFound;
goto bail;
}
pix = PICTTo16BitPixMap(pic);
if (pix == NULL) { err = memFullErr; goto bail; }
Converting PixMaps to Pictures
PixMapToPICT
PicHandle PixMapToPICT(PixMapHandle pix);
PixMapToPICT returns a QuickDraw picture that will draw the image stored in the PixMap. PixMapToPICT is the inverse of PICTToPixMap.
PixMapToCompressedPICT returns a compressed QuickDraw picture that will draw the image stored in the PixMap. PixMapToCompressedPICT uses the QuickTime 'jpeg' compressor. If QuickTime is not installed or if an error occurs, this routine returns NULL.
PixMap2PixPat converts a pixmap to a pixel pattern resource. The pixmap's dimensions should be some power of two (i.e. 8, 16, 32, 64, or 128). If an error occurs, NULL is returned.
WithPixMap is a macro facility that sets up the drawing environment such that any drawing commands in the statement following the macro instantiation will draw into the PixMap handle provided as the first parameter. pix is a PixMapHandle, pxmp is a variable of type PixMapPort*. You must define these variables yourself. For example,
PixMapHandle pix;
PixMapPort* pxmp;
EXAMPLE:
PixMapHandle pix;
PixMapPort* pxmp;
pix = Make16BitPixMap(100, 100);
if (pix == NULL) { err = memFullErr; goto bail; }
WithPixMap(pix, pxmp) {
MoveTo(30, 30);
DrawString("\pHello World");
}
...
Drawing and Plotting Routines
PlotPixMap
void PlotPixMap(PixMapHandle pix, short h, short v, short mode);
PlotPixMap provides a simple interface for drawing a PixMap in the current GrafPort. The PixMap is drawn with the top left corner aligned with the point (h,v) using the indicated transfer mode.
EXAMPLE:
PixMapHandle pix;
PixMapPort* pxmp;
pix = Make16BitPixMap(100, 100);
if (pix == NULL) { err = memFullErr; goto bail; }
WithPixMap(pix, pxmp) {
MoveTo(30, 30);
DrawString("\pHello World");
}
PlotPixMap(pix, 20, 34, srcCopy);
...
PixMapCopy
void PixMapCopy(PixMapHandle pix, Rect *src, Rect *dst, short mode);
PixMapCopy copies bits from the PixMap to the current port from the src rectangle to the destination using the indicated copy mode.
EXAMPLE:
PixMapHandle pix;
PixMapPort* pxmp;
Rect src;
WindowPtr w;
SetRect(src, 0, 0, 100, 100);
pix = Make16BitPixMap(100, 100);
if (pix == NULL) { err = memFullErr; goto bail; }
WithPixMap(pix, pxmp) {
MoveTo(30, 30);
DrawString("\pHello World");
}
PixMapCopy(pix, &src, &w->portRect, srcCopy);
...
Files in this package
PixMap.c -- source code for the PixMap routines' implementation
PixMap.h -- header file providing interfaces to the PixMap routines
PixExample.c -- implementation file for the example
PixExample.r -- rez file for the example
PixExample -- a compiled example
MakeFile -- make command file, builds the example
:Libraries: -- precompiled libraries, ready to link.
PixMap.o -- 68K version of the PixMap library
PixMap.xcoff -- PowerPC version of the PixMap library
Copies for sale!
These libraries are provided for free and you may use them in any program you make; however, if you would like to purchase a copy of these libraries and have a legal paper trail establishing your right to use them, then send along a cheque or a money order in the amount of $25.00 for the purchase of one copy. I'll send you a receipt.
NO WARRANTY
No warranties are made regarding these files. John Montbriand disclaims all warranties regarding these files, either express or implied, including but not limited to implied warranties of merchantability and fitness for any particular purpose. These files are provided "AS IS" without any warranty of any kind. Use them at your own risk. Copies of these files are not for sale in areas where the law does not allow exclusion of implied warranties.
Bug reports make this a better product!
As in all of my products, I advertise a $10.00 finder's fee for bug reports that lead to corrections. If you find a problem here, report it! it could be worth your while....
Further Reference
PixMap.h and PixMap.c contain routines for accessing and manipulating PixMap data stored in PixMapHandles. For more information about PixMaps, offscreen drawing, Handles, C, etc.. refer to the following sources:
"Pixel Maps" (4-9) in the "Color QuickDraw" chapter of Inside Macintosh: Imaging With QuickDraw by Apple Computer, Inc. Addison-Wesley
A discussion of the PixMap data structure and how it applies to CGrafPorts.
"Copying Pixels Between Color Graphics Ports" (4-26) in the "Color QuickDraw" chapter of Inside Macintosh: Imaging With QuickDraw by Apple Computer, Inc. Addison-Wesley.
A discussion of the Bitmap data structure and how it applies to CGrafPorts.
"Boolean Transfer Modes With Color Pixels" (4-32) in the "Color QuickDraw" chapter of Inside Macintosh: Imaging With QuickDraw by Apple Computer, Inc. Addison-Wesley.
Some discussion of the various transfer modes and how they apply to PixMaps.
Both the "Graphics Devices" chapter and the "Offscreen Graphics Worlds" chapter of Inside Macintosh: Imaging With QuickDraw by Apple Computer, Inc. Addison-Wesley.
Other information related to PixMaps.
The "Image Compression Manager" chapter of Inside Macintosh: QuickTime by Apple Computer, Inc. Addison-Wesley.
Information related to using PixMaps with the image compression facilities provided by QuickTime.
Technical note QD13 "Principia Off-Screen Graphics Environments" by Forrest Tanaka. Apple Computer, Inc.
A discussion of offscreen drawing with PixMaps.
Inside Macintosh: Memory by Apple Computer, Inc. Addison-Wesley.
A discussion of memory management, handles, what they are, and how to use them.
The C Programming Language 2nd edition by Brian W. Kernighan and Dennis M. Ritchie. Prentice Hall.
